What's new

PIVX-Doc-Support-Website

FlorentG74

New Pivian
Code:
Title: PIVX Documentation and Support Dedicated Website
Name: PIVX-Doc-Support-Website
Term: 4
Cycle Amnt: 1 421
Total Amnt: 5 684
Author: FlorentG74
Receiver: FlorentG74
Address: DMrbxvoa11gLfRq4ortzBa1e41neb5MoP9
Created: 31 May 2021
Status: Draft

Overview​

PIVX documentation is available in in a variety of medias, including the PIVX forum - mostly for end-users (i.e. step by step tutos) and the Github wiki (more technical info).
It can make the experience of adopting/using PIVX frustrating as:
  1. Finding resources is a complicated process and
  2. Deprecated resources are left behind and remain online, confusing users.
I wrote an assessment of the current documentation process - available on GitHub: https://github.com/FlorentG74/PIVX-Wiki/blob/master/PIVX-Documentation-Proposal.md
This proposal aims at:
  1. Delivering a documentation website that would offer unified documentation to all PIVX users (new users, advanced users, masternode owners)
  2. Putting in place a maintenance process making it easy for maintainers/contributors to evolve the documentation at the same time as the software

Objectives​

These are the objectives my proposal aims at meeting:
  • Have all user documentation aggregated in one place (technical and non-technical documentation)
  • Offer a structure that is easy to navigate for both new and advanced users:
    • An easy to navigate map with a chronological journey for new users
    • A clean structure allowing easy access to any section of the documentation
    • Search capabilities
  • Support multiple formats of documentation (Text/Images/Videos)
  • Make maintenance easy and accessible to persons with limited technical knowledge; reduce/suppress dependency on Core Developers for maintenance
  • Use existing documentation resources as much as possible

Deliverables​

The main deliverables for this proposal will be:
  • An integrated knowledge base which will
    • Replace the documentation available on the forum/in the github wiki
    • Be based on GitHub/the md documentation format (re-purposing the existing https://github.com/PIVX-Project/PIVX-Wiki that contains mostly deprecated information)
    • Have a maintenance process that allow for external contributions (via pull requests) while implementing tight controls
  • A standalone website (linked to the main PIVX website), serving the content from the knowledge base:
    • A CMS delivering the objectives listed above (Documentation display/navigation/search)
    • A synchronisation with GIT allowing for auto-refresh of the documentation without requiring intervention from a developer. Mechanism for refresh:
      • The website will have a local git repository containing the documents.
      • Addition/Update of documents will be deployed to the website via a 'git pull' from the remote hosted on GitHub (either via a cron or a web hook mechanism)
  • A maintenance process for the documentation that will contain the following information:
    • Structure of the documentation website
    • Process to add/update/remove documentation
An update on the progress and on the usage/distribution of the funds will be provided on the forum on a monthly basis.

Approach & Budget/Resources​


Task
Description
Person in Charge/Beneficiary
Estimated Effort
Distribution
Website - Initial Framework
  • Deliver a website based on Grav CMS (a file-based CMD that is based on the Markdown format)
  • Develop a theme for the CMS that integrates with the PIVX color chart
PalmTree​
30 hrs.​
2*250 =
500 PIV
Website - Enhancements throughout the proposal
  • Implement enhancements to the basic framework throughout the course of the proposal
FlorentG74/PalmTree depending on requirements​
30 hrs.​
500 PIV
Knowledge Base - Structure
  • Define a structure for the knowledge base, and create site map/placeholder pages
FlorentG74​
5 hrs.​
74 PIV
Knowledge Base - Migration from forum
  • Migrate all up-to-date articles from the forum to the new pages
  • Flag the deprecated content for suppression
FlorentG74
Open to contributors for 30 PIV/Article​
18 articles / 30 PIV per article​
540 PIV
Knowledge Base - Review of Youtube videos
  • Review Youtube videos / flag the deprecated ones for suppression
  • Where available and relevant, integrate the video on corresponding wiki page
FlorentG74
Open to contributors​
20 hrs.​
300 PIV
Knowledge Base - Troubleshooting section
  • Review the questions on the Support forum/Discord and incorporate the frequent/relevant ones into the doc articles/troubleshooting sections
FlorentG74​
20 hrs.​
300 PIV
Knowledge Base - Add Content
  • Proposal is to organize the documentation in 10 different sections
  • Each section would have a lead contributor receiving a distribution after works has been peer-reviewed
  • The 10 sections would be:
    • Introduction to PIVX/Main Concepts - 150 PIV
    • Getting started - 600 PIV
    • Using the QT Core Wallet - 500 PIV
    • Staking - 400 PIV
    • Using the Command Line Core Wallet - 300 PIV
    • RPC Client - 400 PIV
    • Governance - 200 PIV
    • Masternodes - 200 PIV
    • Best Practices / FAQ - Shared work among all contributors, no explicit distribution
    • Glossary - Shared work among all contributors, no explicit distribution
FlorentG74
Call to contributors​
Up to 2750
Project Management
  • Coordination of the contributors
  • Coordination of the reviews
  • Coordination with the community for questions/clarifications etc.
  • Definition of the framework for the longer term maintenance of the documentation
FlorentG74​
48 hrs.​
4*180 =
720 PIV


Total
Total AmountCycle Amount
5 684 PIV1 421

Assumptions & Risks

  • Hosting/linking to the main website: As per discussions with @palmtree and @Kyeno, hosting and integration on the main website are unlikely to require specific budget lines.
  • Some of the deliverables (the content ones) depend heavily on the community. While I will strive to get the whole scope delivered in 4 terms there is a possibility that some topics will not be covered during the lifespan of the proposal. Any budget remaining after the full term will be used to either complete the deliverables listed above, or be used towards some of the stretch objectives if all deliverables have been completed.

Potential Stretch objectives

The following objectives will be considered if time allows but are not covered by the proposal/budget request (in particular as they have dependencies on Core/Web developers)
  • Update the Core Wallet to include a link to the documentation website
  • Update the Core Wallet FAQ to point to a wiki page to simplify maintenance
  • Have a bot repost the messages from the support section of the forum on Discord to ensure all support requests are seen by the team

Out of scope items

The following items should be considered as out of the scope of this proposal:
  • Developer documentation (contribution/translation/compilation etc)
  • New Youtube videos; I don't have the skills / time and believe this should be part of a separate proposal

About myself

I'm a relatively new member of the PIVX community, and am a strong believer in the value of PIVX.
While researching the coin/setting up my wallet for staking I have experienced first-hand the challenges new PIVX adopters can face in terms of documentation.
I have contributed to the PIVX project as a translator during the month of May (on both the Core Wallet and the website), which gave me visibility on all the content available online to the PIVX community.
 
Last edited:
To answer your questions ...

Hosting should be pretty easy to add to an existing server. Not familiar with the tech stack chosen though. Check with @Kyeno for compatibility.

I would think that updates to the PIVX.org website are just editing links. Again - check with @Kyeno for impact.

If you are concerned that some deliverables will be missed due to lack of Community support (good point) I would suggest you spread out the work over 4 months, or more.
There is no mechanism to refund treasury amounts received. You need to deliver within reason or your reputation takes a hit. Hence the suggestion to stretch it out. Also, it makes it easier for it to pass each month if the cycle amount is less. Having said all that, it is OK to report out at the end, that you still have funds remaining, and also have work to complete. It is more about transparency and accountability than hitting an exact deadline. For example, nothing wrong with the report at the end of the last cycle being; "Hey everyone; we got 80% of the deliverables done, and we still have budget remaining for the balance. Things just take longer than I expected. So, the remaining part of the proposal effort will get completed - just need a bit more time. I will report out again in 4 weeks." But, it does look better on your project management skills if you indeed do hit the deadline. ;)
 
Thanks both for your feedback.
I've reached out to Kyeno to advise on the core website aspects.
Eric I'll update the pre-proposal to take your comments into account I think it makes sense to stretch it for a bit longer to make it lighter on both people and budget
 
Sorry - something is not clear to me.
The raw data will be held and maintained in a Github repo for the PIVX Project, but will be 'displayed' on the documentation website?
Basically, I am trying to wrap my head around where the 'master branch' is, and what is a remote of that repo.
 
I've updated the pre-proposal following discussions with Kyeno today on the core web part and comments received here/on Discord.
Main changes:
  1. Proposal/distribution schedule split across 4 cycles
  2. Addition of a monthly reporting on progress/budget for transparency
  3. Open question' section changed to 'Assumptions & Risks' and including responses from community members
@Eric_Stanek regarding your question on data maintenance: I've detailed it a bit more in the proposal; essentially I am thinking about using the current PIVX-Wiki repository as a remote, and have a local repo on the web server that would be refreshed regularly (via 'git pull' from the remote GitHub repo). This could be scheduled daily so that any update on GitHub would be reflected on the website the next day.
Does that clarify?
 
@Eric_Stanek , Git Sync can work bi-directionally. Changes to github content can sync to the website. Local website changes can also sync back to github. This allows for ad-hoc version control and also the ability to see the edit history, even if the content originated from a website content editor.
 
Top