openownership / bods-dev-handbook Goto Github PK

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.

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.

• Clarification over when icon labels (e.g. Person A) should be included
• Guidance around the background rectangle sizing (e.g. should all rectangles in one diagram be the same width, or by row, or by statement type, or simply by text content)
• Guidance on when text should sit on a new line (e.g only when exceeding the box width, only for separate fields)
• Guidance on what takes precedence - box sizing or font sizing

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.

Update guidance on capitalisation following resolution of openownership/data-standard#341

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.

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.

It's not clear how to do this atm.

Should cover:

• adding tests for valid statements / packages;
• adding tests for invalid statements / packages;

Running the tests.
Running flake8.

Include:

• Not using Google Draw for text (atm)
• Using newlines and not expecting text wrapping to work
• Including space for strings to 'expand'
• Ensuring alignment set correctly on text (so that translated strings, if longer, will expand in the right direction)

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?

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.

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

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.

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 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.

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:

http://example.com

(GitHub renders bare URLs as links even without angle brackets – try it in a Markdown file.)