Writing Docs - Ideas

[rufuspollock]

A place for collecting ideas for writing good docs.

Tech

Used to be sphinx but now mkdocs seems to be making an advance.

A Minimum

README

Going Further

Links

https://jacobian.org/writing/great-documentation/

http://www.writethedocs.org/guide/#contents

[danfowler]

As part of this task, we should document how to deploy your good README.md file to the relevant repository so that it remains readable. For example, PyPI can't read Markdown documents, so many of our PyPI pages are unreadable. While we convert README.md to README.rst using pandoc in our Travis config, we have to make sure that skip_cleanup: true is set in the deploy dict of the .travis.yml file so that it actually gets uploaded to PyPI.

[roll]

@danfowler
I've fixed our FD python packages and added your fix to oki-py

[danfowler]

Great! I don't see the commit yet in https://github.com/okfn/oki-py