Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate out reference documentation for command line arguments and config file #1300

Closed
2 tasks done
micahellison opened this issue Jul 10, 2021 · 1 comment · Fixed by #1332
Closed
2 tasks done
Assignees
Labels
documentation Improvements or additions to documentation 📌 This can't go stale

Comments

@micahellison
Copy link
Member

micahellison commented Jul 10, 2021

Documentation Change

jrnl's documentation is somewhat incomplete but also a bit inconsistent in its approach. We get a fair amount of issues that I think are more about the problems with the docs than the program itself.

Lots of mature software projects tend to divide up documentation into four main areas:

  • Tutorials - "getting started" and other quick introductions to the app with a little bit of context
  • Topic guides - meant to help the user get an overall understanding of the concepts behind the application
  • Reference guides - granular, technical reference
  • How-to-guides - our recipes section

I think we've done a good job on tutorials, but we've kind of mixed up the other three categories. In particular, some of our documentation seems to be trying to be both tutorial and reference at the same time and I think that hurts its ability to meet either need.

At the very least, we should add:

  • a reference guide for jrnl's arguments
  • a reference guide for jrnl's config file keys

Once those two are added, we should rework the rest of the documentation that addresses arguments and the config file as necessary.

Affected Page(s)

Other Information

This piece on four types of documentation helped orient me towards this approach.

@micahellison
Copy link
Member Author

When this issue is complete, I think it will resolve #995 as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation 📌 This can't go stale
Projects
None yet
2 participants