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

Refactor documentation into smaller pages (to make it more readable) #118

Closed
jwflory opened this Issue Feb 1, 2019 · 2 comments

Comments

1 participant
@jwflory
Copy link
Member

jwflory commented Feb 1, 2019

Summary

Break up documentation from single, monolithic pages to more modular, bite-sized pages

Background

We have documentation, but it is not easy to read. It is wordy and sometimes confusing. Our docs should take on small topics and focus on those topics. This also helps our documentation's searchability and makes it easier to navigate (in other words, important information isn't buried).

Details

The installation page is in need of the most love. This page could be 3-4 pages. I was thinking to split it up this way:

  • Quick installation guide (i.e. numbered steps about how to do a fast install)
  • Create Telegram bot
  • Configure IRC channel
  • Explaining the config file
  • Deployment options (currently Usage section)
  • Maybe more…?

Outcome

Documentation is more useful to non-developers, easier to find key information, better visibility into different parts of Teleirc

@jwflory jwflory self-assigned this Feb 1, 2019

@jwflory jwflory added this to To do in Teleirc development Feb 2, 2019

@jwflory jwflory added this to the v1.3 milestone Feb 2, 2019

@jwflory

This comment has been minimized.

Copy link
Member Author

jwflory commented Feb 2, 2019

Discussed in 2019-02-02 RITlug developers' meeting. This issue is targeted for the v1.3 milestone, estimated to release on March 2nd, 2019.


I volunteered to work on this during this sprint. It's something I've wanted to do for a long time. I'm targeting for completion the Saturday, Feb. 16th developers' meeting.

I'll probably start working on this in a feature branch gradually.

@jwflory jwflory moved this from Current sprint to In progress in Teleirc development Feb 9, 2019

@jwflory

This comment has been minimized.

Copy link
Member Author

jwflory commented Feb 9, 2019

Discussed in 2019-02-09 RITlug developers' meeting.


Not yet started. I plan to split off main installation page into several smaller pages. Expecting the main docs page to be split up by next developers' meeting on Saturday, Feb. 16th.

jwflory added a commit that referenced this issue Feb 15, 2019

docs: Add config file glossary
Part of issue #118.

This commit adds a new page for a configuration file glossary. This page
is a highly-detailed overview of the config file and what each setting
does in the `env.example` file. It is intended for advanced users.

For now, this commit does not pull the duplicated parts out of
`installation.rst`, but I plan to deprecate that page in a future pull
request.

jwflory added a commit that referenced this issue Feb 15, 2019

docs: Add new page to explain how to deploy Teleirc
This commit is part of issue #118.

A new page is added specifically to explain how to deploy Teleirc. It
consolidates the **Usage** section from `installation.rst` and all of
the `using-docker.rst` page. This commit intends to make deployment
options more clear and easy to understand.

Some methods were removed, like the ArchLinux package. It is many
updates behind on the bot, so I think it's better to recommend people to
use directly from source where possible.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Add config file glossary
Part of issue #118.

This commit adds a new page for a configuration file glossary. This page
is a highly-detailed overview of the config file and what each setting
does in the `env.example` file. It is intended for advanced users.

For now, this commit does not pull the duplicated parts out of
`installation.rst`, but I plan to deprecate that page in a future pull
request.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Add config file glossary
Part of issue #118.

This commit adds a new page for a configuration file glossary. This page
is a highly-detailed overview of the config file and what each setting
does in the `env.example` file. It is intended for advanced users.

For now, this commit does not pull the duplicated parts out of
`installation.rst`, but I plan to deprecate that page in a future pull
request.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Add new page to explain how to deploy Teleirc
This commit is part of issue #118.

A new page is added specifically to explain how to deploy Teleirc. It
consolidates the **Usage** section from `installation.rst` and all of
the `using-docker.rst` page. This commit intends to make deployment
options more clear and easy to understand.

Some methods were removed, like the ArchLinux package. It is many
updates behind on the bot, so I think it's better to recommend people to
use directly from source where possible.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Add new page to explain how to deploy Teleirc
This commit is part of issue #118.

A new page is added specifically to explain how to deploy Teleirc. It
consolidates the **Usage** section from `installation.rst` and all of
the `using-docker.rst` page. This commit intends to make deployment
options more clear and easy to understand.

Some methods were removed, like the ArchLinux package. It is many
updates behind on the bot, so I think it's better to recommend people to
use directly from source where possible.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Refactor installation page to quick install guide
This commit closes #118.

The existing documentation is divided into smaller, more manageable
pieces. While there are still improvements that could be made, the work
done across #120, #121, #122, and this commit is sufficient to close the
issue.

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Refactor installation page to quick install guide
This commit closes #118.

The existing documentation is divided into smaller, more manageable
pieces. While there are still improvements that could be made, the work
done across #120, #121, #122, and this commit is sufficient to close the
issue.

@jwflory jwflory closed this in #124 Feb 16, 2019

Teleirc development automation moved this from In progress to Done Feb 16, 2019

jwflory added a commit that referenced this issue Feb 16, 2019

docs: Refactor installation page to quick install guide
This commit closes #118.

The existing documentation is divided into smaller, more manageable
pieces. While there are still improvements that could be made, the work
done across #120, #121, #122, and this commit is sufficient to close the
issue.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment