-
-
Notifications
You must be signed in to change notification settings - Fork 4.1k
Season of Docs projects
The tldr-pages project is applying to the Season of Docs 2021 program. The following are some ideas for potential projects that technical writers can apply to work on. Feel free to reach out to our community chat room on Gitter for any additional information or clarifications.
The main goal of this project is to modernize and properly specify a complete, extensible and unambiguous syntax for tldr-pages. It is expected that this project would build upon the work initiated in PR #958.
The current syntax of tldr-pages entries was decided early on in the project, and all the different clients have been implemented based on that loose specification. Unfortunately, this results in several setbacks that have prevented the project to evolve to satisfy needs identified by the community. In particular, the current syntax:
- is quite loose and underspecified, which ironically leads to some rigidity and lack of extensibility, because any improvement requires all the clients to be updated individually
- is based on markdown, but not fully compliant with it; this means pages can't be properly rendered by regular markdown processors and produce semantically meaningful output
- fails to adhere to common command line usage description patterns, e.g. the POSIX Utility Argument Syntax and the specification defined by the docopt project
- has quirks such as the need for backticks around commands that make both authoring and reading the pages more cumbersome than necessary.
Successfully completing this project would entail fulfilling the following goals:
- A well-defined syntax should be specified, that resolves all the issues identified so far with the current syntax, or at least reaches reasonable compromises for conflicting requirements, if there are any.
- The authors and contributors to the major clients (node.js, python, ...) should be contacted to make sure the new syntax is supported.
- All existing pages in the repository should be converted to this new syntax
- The syntax linting rules should be updated or rewritten, to allow automatically assessing pull requests against the new page format.
- Clients could simultaneously support both the new and the current syntax, during a transition period.
- The content in the old format should remain available for clients that can't be updated, e.g. by publishing an archive of the old-syntax pages.
- CONTRIBUTING.md § markdown format: the primary specification of the current syntax
- style-guide.md: a more detailed description of the current syntax
- Issues labeled "syntax": proposed enhancements to the current syntax that hopefully could be addressed once this project is complete.
- PR #958: a concrete proposal for such a syntax update. The discussion in that pull request contains many relevant points that this project should address.
Markdown formatting; basic scripting of repetitive tasks; communication with multiple stakeholders in an open, collaborative ecosystem (client authors, PR submitters, project maintainers, etc.).
tldr pages are not limited to the tools available in popular systems (either installed by default or available in the software repositories); that said, comparing completeness against well-known collections of CLI tools is a good way to ensure coverage of the needs of most users.
The main goal of this project is to reach full parity with various popular sets of CLI tools, and is comprised of several sub-goals:
- Create all missing pages from the GNU Core Utilities (
coreutils). Tracked in #2213. - Create all missing pages from util-linux. Tracked in #2214.
- Create all missing pages from the "Who needs a GUI?" article. Tracked in #1162.
- Create pages for the individual "page request" issues marked with the help wanted label.
- Achieve +90% coverage in the compound coverage meter on this spreadsheet (includes the lists above and several others).
- Implement an automated check to test and report coverage against various lists. Tracked in #1070.
- Merge duplicate pages from
linux/andosx/intocommon/(checking not just for availability, but for compatible interfaces as well — e.g. GNU vs. BSD versions of the same tool).
Interpreting manpages; experimenting with CLI tools (possibly in multiple systems).
See also the list of projects for the coding programs like GSoC or GCI.