New initiative: Syngrafias

This is where the project is being developed

https://github.com/t0xic0der/syngrafias/

What is this initiative about?

• This initiative is about introducing a web application in the document's workflow to facilitate easier and seamless editing of documentation and wiki pages. The application provides for workspaces, the identity of which can be shared amongst collaborators for interest for allowing them to review the work and/or contribute to the work.
• The changes made to the workspace are immediately processed in the client-side AsciiDoctor processor to bring out a preview of how the documentation would look like when hosted on the documentation sites. Also, these changes are synchronized to all the users connected to a workspace in real-time so they can see/modify the changes you make.
• The Unity Mode is targeted towards a conventional documentation editing scenario where multiple users can come together, edit and review the documentations in real-time while the Cellular Mode is oriented towards serving as a note editor for meets or as interactive notepad for sharing among developers.

Why this initiative?

• The current workflow of the documentation team for editing a document is as follows,
  • First, fork a repository which contains the document that needs editing.
  • Second, clone the fork to their local storage.
  • Third, create and checkout a branch.
  • Fourth, make the proposed/requested changes in the branch.
  • Fifth, build the documentation locally using Antora.
  • Sixth, check if the preview works fine - if not fall back to fourth step and repeat.
  • Seventh, once satisfied with the changes, make the commits and push them.
  • Eighth, make a PR against a deployed branch and wait for review.
• There can be other nuances to the workflow as well and I apologise if I missed out on some important steps in between but I believe that the above points, more-or-less, cover the important parts of the workflow in an abstract manner. Note that this workflow works just fine but that is not to say, that it cannot be improved upon.
• Fedora, being a cross-cultural community, with folks from across a variety of work domains in their life - the use of Git and Antora in documentation management limits the accessibility to a certain extent to only the technical folks (or insists them to learn the same - which is a good thing, I think)
• The initiative would help reduce the apparent effect of version control (by automating the commits) on users, and keep off from the repeated build-and-preview cycles of checking how the edits look for a commonplace or technical users alike, who would appreciate a simpler workflow for something as simple as correcting a typo.
• Even, the review process of the documentation changes can be streamlined by simply sharing a workspace identity with the reviewer so that they can take a look at it and make necessary suggestions at their end without even cloning their fork, checking out that branch and building it to take a look at the changes.
• The Cellular Mode can work as an alternative to the likes of HackMD etc. for making notes and sharing notebooks with multiple cells whenever a meeting is going on. The cellular nature of the workspace enables unintrusiveness across multiple cells and the freedom to solely editing a cell by locking its access.

Definition of success

Minimal outcome

• Completion of the development of the project and integration with FAS to retain the edits persistently.
• Adoption of Syngrafias Unity Mode in the tool-chain of documentation creation and reviewing.
• Adoption of Syngrafias Cellular Mode in the toolchain of note-making and discussion during meets.

Really nice to have wishes

• Contributors. (Loads of em)
• Conversion of the entire front-end to React JS.
• Graphical DIFF utility to denote documentation changes.
• Delta-algorithm to avoid syncing the entire cell or page.
• Responsiveness across variable widths and heights.
• Function rewrite to improve code readability.

Area/community impacted

• With the Unity Mode, the initiative makes an impact at mostly the documentation team.
• With the Cellular Mode, the initiative aims to make an impact throughout the entire community by providing them a workspace to make synchronized notes and share them at will.

(of both Fedora and CentOS users as well as contributors)

Dependencies

Software dependencies

• Flask (https://flask.palletsprojects.com/en/1.1.x/)
• Websockets (https://websockets.readthedocs.io/)
• Asyncio (https://docs.python.org/3/library/asyncio.html)
• Click (https://click.palletsprojects.com/en/7.x/)
• jQuery (https://jquery.com/)
• Fomantic UI (https://fomantic-ui.com/)
• CryptoJS (https://www.npmjs.com/package/crypto-js)
• React JS (https://reactjs.org/)

Skills needed

• Understanding of how the current documentation workflow functions.
• Understanding of the aforementioned software dependencies.

Involvement

• Preferably someone who can assist with deployment and assigning a subdomain.
• Active contributors to help build/refine to attain the aforementioned features.

Works prior to this initiative

Not that I know of.

Deadline

The sooner, the better.