-
-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Season of Docs projects
The tldr-pages project is participating in the Season of Docs 2019 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).
Projects listed below are here for reference and not being considered for the 2019 Season of Docs program.
There are currently three lists of clients, each maintained independently.
We want the client lists to live at a single place, so that the lists won't get out of sync nor outdated.
The goal is to merge the three lists without losing any relevant information, but keeping it readable.
The final list can live at either of the three existing places, or at a new location (e.g. a new CLIENTS.md file).
The existing locations should either embed or link to the unified list.
Links to the existing lists:
- README: tldr-pages/tldr:README.md#clients
- Wiki: tldr-pages/tldr/wiki/TLDR-clients
- Website: https://tldr.sh/#installation
Markdown formatting; collaborative development using git and GitHub.
Pages now support adding a link to the tool's homepage, but many are still lacking it. The goal of this project is to ensure all pages have a link that people can follow to learn more about the tool and explore more comprehensive documentation.
For reference, see the following PRs where multiple links have been added:
Web research; collaborative development using git and GitHub.
See also the list of projects for the coding programs like GSoC or GCI.