Best practices for open source documentation

FLOSS

(Free Libre Open Source Software)

issues to address:

- Documentation

- Managing Code

- Managing People

- Managing Releases

- Community

- Events

Documentation is frequently hard. In-code is sometimes done well, but there's anything else which we usually don't do well.

Makedocs: make docs in simple markdown language, and submit to github to generate docs

another hack: sometimes write tests in a literate style -- write the explanation of how the code is supposed to work, embedded into the test. Example tool that do that: cucumber.

for backdrop: three kinds: - every function has a definition and a paragraph, a file in every module has definitions also. - a user guide, webpages instruction for end users. - all the api docs are pulled into API website with pages also for developers

ongoing problem is one part might be updated while another isn't so the dev docs don't match the api docs, etc.

for Backgrop: - one core committer whose main job is documentation - completely different set of people who are responsible for the end user documentation, since it's a differnt skillset, don't need to use git - when you change the function definition you're required to change that doc.

another hack: a "meta documentation page" -- how, when and why to document. spells out the expectations, for being a developer on the project.

- another approach: having a second issue for "Docs" automatically created when an issue is filed.

- another approach: File the documentation issue first, and that triggers a review of what you're going to create, and help reduce the possibility of writing something that's unneeded or already being worked on. Maybe not scalable to very large projects like Drupal.

-- People

Paying contributors is good, but does it make it more likely that volunteer contributors won't feel like it's needed since someone else is getting paid?

CiviCRM has both paid staff and volunteers, Backdrop has only volunteers, but thinking about it. CiviCRM was mostly paid at the beginning, but the mix has changed over time. As they try to be more sustainable, has cut back on paid. However, a lot of the people who are volunteering time do have some sort of financial case or professional capacity for it. E.g. they work for a company that is using the software so they want to improve it.

Besides money, there's also a lot of context being passed back and forth among the paid people which makes it harder for the volunteer developers to join in, and know the priorities and decisions that have been made.

Can help to have clear milestones that people can see what's happening and prioritized.

We can also lose the thread of the thinking behind decisions in closed github issues and old slack discussions -- can make it easier for people to plug in by putting that into documentation.

-- How to Make it easier to get started

good example: Hoodie They actually spend time training people how to commit. Great surge in commits.

anti example: nodeJS "terrifying" to get involved.

- Good to have good separation of concerns, so you can work with the frameworks and tools that you know, without having to know all the parts that go into it.

- doing full reviews, like a training exercise, for PR's, can draw people in.

Need to see it as your *job* to review and pull people in, rather than as a pain.

SUper Useful to have a mentor. New person can be afraid they're going to break something, helps not be afraid, show them how to be effective. Deal with all the "assumed knowledge" in documentation, etc.

The Dark Side: what if someone really just wants you (the maintainer) to show/teach them how to do something with the software because they have been hired to do it by a company and don't know how. I.e., commercial developers being free riders on open source maintainers.

Options: radical honesty. "That's not what this project is for." Redirecting them to the documentation or somewhere away from you.

- It can be important and useful to have a *Community* around the software, social places to talk to people about the work that you want to do with the tools, even if they don't have tech skills but have similar interests.

- Also good for projects to offer resources for new potential users of the software to contact current users to figure out if it's fit.