Developer Tools & Documentation Session

Session Leader: MateuszPiotrowski

Notes: https://hackmd.io/bkIVXMoKR_---xxIKpn9_w?edit

• Make it easier to use/keep the documentation up to date.
• Make the documentation more accessible.

• Convert good wiki articles into document.
• Make contribute to the doc tree easier.
• Editing wiki is comparably easier than XML and is similar enough to e.g. markdown.

• GitHub accounts for creating bugs, so that people can re-use their already existing accounts without having to create a separate one just for filing the bug
• Use OAuth or similar authenticator to integrate with GitHub, Google, etc. to make people re-use their accounts there
• https://wiki.mozilla.org/Bugzilla:OpenID_Auth_Plugin (not maintained, but maybe there is another one that is)
• This one is used by Mozilla in production: https://github.com/mozilla-bteam/bmo/tree/master/extensions/GitHubAuth and https://github.com/mozilla-bteam/bmo/blob/master/github.cgi to go along with it (from dch).

• Q: Unknown, when to close the bug.
  • A: After an MFC is done. Mark it as awaiting MFC and as soon as it is done, close the bug.
• Assigning mailing lists is not a good idea, because no one feels responsible
• “Label” bugs for people looking for specific areas instead of using mailing lists
• Bugzilla states and flags don't work
• A workflow for Bugzilla is needed or documentation on how to use it for people who have not used it before

• https://mfc.kernelnomicon.org/

• SSO
  • Kerberos (needs to be supported by the systems we use for logins)
  • OAuth
• MFA

PaulWebster is already working on a new FreeBSD wiki using XWiki

• Make things ridiculously easy to contribute changes to the docs.
• XML is too tedious to learn for drive-by contributions.
• Move documentation to GitHub?
  • Quick rendering of results
  • Web-based editor with live-preview
  • Markdown (no one should see the XML behind it like it is now)
  • review process (from a doc committer)
  • style guide that should apply for contributions

• PostgresQL uses SGML (similar to us) but they have a Django app to help with the boring bits.
  • https://github.com/postgres/pgweb

• Use the wiki as a scratch space to eventually (once stabilized enough) move it to the handbook.
• Hardware support (i.e Graphics support) should not be in the handbook, but go into the hardware notes for a certain FreeBSD release.
• Tutorials should go into separate articles
• Expiration dates for entries
• Move FAQ to a stackoverflow.com-like site

1. Git has become the de-facto source control system.
2. Augment Phabricator to be more than just a review system.
3. We can't have git in the base system due to licensing issues.
4. We need to let git users do contribution easier

• Dynamic at first, but becomes static (unchanged) once curated after the submission deadline has passed and is published
• Does not have many dependencies with the rest of the doc system and could be a separate thing
• We need a better way to make it easy to contribute a report with a preview function
• CouchDB moved from DocBook to another system (RST) years ago and drive-by contributors becoming committer was quite low, but generally was viewed to be better than before (better cross-referencing, Sphinx integration)

• Integration, Linking
• XML DocBook is not just for representation

Types of contributors:

• doc committers
• drive-by contributors
• developers, who want to document the thing they were developing

• Triggers for various functions and checks (man page changes, checking if all the options are documented in the man page, etc)
• Feedback cycles are too long when changes should be made
• Filters in Phabricator could find/reference places that should also be changed when someone makes changes in a source file

Team up developers and doc people early so that the doc committers can document it (for testers, early adopters). As the feature changes, the changes are also documented which is much less work bulding upon already existing documentation. Once the feature is stable enough to be released, there is already documentation available that can go in to the handbook. That way, a new FreeBSD release has a new feature and the accompanying documentation available.

• encourage/require people also put commit message when submitting a patch to code review system