Skip to content

Commit

Permalink
docs(about): Improve wording in the Why section
Browse files Browse the repository at this point in the history
  • Loading branch information
imAsparky committed Jul 9, 2021
1 parent 92fb3d9 commit ec5c76e
Showing 1 changed file with 19 additions and 6 deletions.
25 changes: 19 additions & 6 deletions docs/source/about.rst
Expand Up @@ -2,79 +2,92 @@
About
=====

|
JUNCTION BOX
------------

What's in a name?
~~~~~~~~~~~~~~~~~

|
The process of writing software is very similar to the electrical trade in the sense that things are wired up or connected.

Hence the name **Junction Box**, a place where things are connected.

|
Overview
---------

|
This project is about documenting how we use several technologies that meet the needs of our software development initiatives.

|
What
-----

|
To kick-off, we will be exploring and documenting these technologies:

#. `Diátaxis <https://diataxis.fr/>`__: A documentation content organisation framework.
#. `Sphinx <https://www.sphinx-doc.org/en/master/>`__: A document building tool.

|
When how we use the first two items has been documented, other technologies on our list include:

|
#. `Continuous Delivery <https://www.youtube.com/channel/UCCfqyGl3nq_V0bo64CjZh8g>`__: Dave Farley Style.
#. `Django <https://www.djangoproject.com/>`__: A python web framework.
#. `Pytest <https://docs.pytest.org/en/6.2.x/>`__: A software testing tool.
#. `Hypothesis <https://hypothesis.readthedocs.io/en/latest/index.html>`__: A software testing tool.
#. `Playwright <https://playwright.dev/>`__: End-to-end testing for modern web apps

|
How
---
|
#. Create and follow a style guide.
#. Create standard layouts for content.
#. Follow the Diátaxis document content framework.
#. Only record what we have used and tested.

|
Why
----

|
Documentation is a critical task often overlooked or poorly executed.
Over time as memories fade or moved on to other tasks, good quality project or business documentation becomes evident.
Continuous documentation is a critical task often overlooked or poorly executed.

Over time as memories fade, the need for good quality documentation becomes evident.

Often things that make sense now, while our brain is working in that context, don't make sense later.
Things that make sense now often don't make sense later.

Good documentation can reduce the load when it is needed.
When it is needed, good documentation can ease the load of remembering.

*This may help some one else!*

|
When
------
|
Following Continuous Delivery Principles, this is a living document.

|
The Author
----------
|
Mark Sevelj has an electrical trade background.

Roles where often technical and using Python and pandas for data analysis was a lot faster than excel.
Expand Down

0 comments on commit ec5c76e

Please sign in to comment.