f4pga / ideas

Random ideas and interesting ideas for things we hope to eventually do.
86 stars 9 forks source link

SymbiFlow projects documentation audit #56

Open kgugala opened 4 years ago

kgugala commented 4 years ago

Since even the best project will have a limited impact if its README is poor, it is crucial that the documentation is comprehensive, thus making it easier for developers to use the project and contribute to it.

In this task you will perform an audit of documentation in order to verify its completeness, correctness, accuracy and wording. The task will involve close collaboration with developers and engineers to try to anticipate the users’ questions and issues even before they run into them.

You will need to make sure that the documentation provides all relevant information structured in a logical sequence and a consistent manner. Also, your job will be to keep the README as short as possible while still describing the core functionality and the launching steps. To maintain the highest standard of the documentation you will need to make sure it has proper formatting, is organized into sections, includes a table of contents, contains an attention-grabbing introduction and provides a high-level summary. This will make navigation easier and improve the overall clarity of the document, making it more appealing to the user. As part of the job you might need to familiarize yourself with basic Markdown syntax and basic UX principles.

The repositories that require auditing:

Additional information could be obtained from:

mithro commented 4 years ago

Don't know if related, but there is also the Google Docs folder which has a lot of unorganized documentation around various aspects of the project, including a lot of nice diagrams.