openownership / bods-dev-handbook Goto Github PK
View Code? Open in Web Editor NEWGuidance for BODS schema development and related things
Home Page: https://openownership.github.io/bods-dev-handbook
License: Apache License 2.0
Guidance for BODS schema development and related things
Home Page: https://openownership.github.io/bods-dev-handbook
License: Apache License 2.0
https://www.python.org/dev/peps/pep-0440/
This means that we can use the "warning banner on old versions" feature in Read The Docs in the future.
This section of the docs needs to be brought up to date, now that we've moved to using GitHub Discussions for feature implementation proposals.
Once that's done we should also remove the original Implementation proposal ticket template from the repo.
Details in this issue on the data standard repo. Translation guidance from the data standard README and added to the translation page of the handbook.
A couple of points I've come across when following the style guide for diagrams while working on the nominee page that would be useful to have clarification on.
Of course, as we cover more complex topics in the documentation these may need to flex, but a starting point would be useful for consistency.
Instead of a list like https://openownership.github.io/bods-dev-handbook/tools.html, we have an Airtable accessible from https://www.open-contracting.org/resources/open-contracting-tools-directory/
We're not entirely satisfied with the available views within Airtable, but we'll continue to use it at least for data entry, as Airtable offers an API, with which we can create other views whenever we decide to.
Feel free to close this issue, as just knowledge sharing.
From https://openownership.github.io/bods-dev-handbook/this_handbook.html
A little-known feature of Markdown is that you can link bare URLs with angle brackets, e.g.
<http://example.com>
becomes:
(GitHub renders bare URLs as links even without angle brackets – try it in a Markdown file.)
We need to write down why/how we create branches, name them, monitor their use and manage their merging and deletion etc. Prob standard dev stuff, but it needs to be written down for the sake of all who work in the repo.
I think GitHub Pages makes a lot of sense.
The OCDS handbook uses Sphinx, but doesn't take advantage of any of its features, really. We have some other process documentation in Google Drive, and we're considering combining both into Gitbook (free for open-source), as it retains the features we use from Google Docs and is simpler to edit and deploy than Sphinx+ReadTheDocs.
Feel free to close this issue, as just knowledge sharing.
I've put some ideas about writing style for the schema and for the docs here:
https://github.com/openownership/bods-dev-handbook/blob/master/style_guide.md
@ScatteredInk @siwhitehouse - what do you think of these initial ideas?
I've added a placeholder here https://github.com/openownership/bods-dev-handbook/blob/master/compiling_schema.md#codelists.
Could one of the devs take a look and document what they can on the technical side? (Assigning to James in the first instance.) We'll need to think about the actual workflow around making a change to a codelist; i.e. do we only sync the schema to the codelists (if there have been edits) as part of a pre-release-freeze process?
It's not clear how to do this atm.
Should cover:
Running the tests.
Running flake8.
Some useful guidance on how to edit and maintain the reference.rst page in the docs is needed. The page makes heavy use of custom sphinx directives and options and their use should be explained. Additionally, the page should be kept in alphabetical order and link anchors maintained.
Anything to add here @siwhitehouse?
The current draft says:
use 'entity,' 'legal person' or specific descriptors like 'trust' to describe legal entities
This is potentially confusing as a trust is not a legal entity (i.e., it doesn't have legal personhood). To some extent this is a function of the confusion in the schema, where all non-natural persons are described as types of entity, but the human-facing documentation should address that issue.
I think this could be solved by being explicit about the FATF-aligned distinction between legal persons and legal arrangements. So the above could become something like:
use 'legal entity,' 'legal person' or specific descriptors like 'registered company' to describe entities with legal personality
use 'legal arrangement' or specific descriptors like 'trust' to describe legal arrangements
Update guidance on capitalisation following resolution of openownership/data-standard#341
In the list of validation keywords format
isn't an option. I couldn't get an invalid test to work with an incorrect uri without using format
in the expected_errors.csv. I can see though that format
isn't listed in https://json-schema.org/draft/2020-12/meta/validation so I'm not sure if this is correct or what keyword to use instead?
Include:
We should make this easier to navigate by changing the theme to one with a side menu that shows the contents. Just The Docs is nice.
I think this section of the dev handbook is now slightly out-of-date following openownership/data-standard#404, and should clarify the difference between editorial changes to the docs and working on the theme.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.