search

pythonindia / junction

Junction is a software to manage proposals, reviews, schedule, feedback during conference.
MIT License
192 stars 185 forks source link

[Suggestion] Restructuring documentation #697

Open miphilomath opened 4 years ago

miphilomath commented 4 years ago

Since Junction's documentation is distributed at various places and requires restructuring, I would like to propose the following structure for the readthedocs documentation, suggesting appropriate location for the existing documentation on GitHub wiki. Creating a structure before writing pages will help us write individual pages and recollect them easily.

I suggest to have 4 level of documentation:

  1. Welcome Page

    • With table of contents reference for whole project for easier and efficient navigation.
    • Link to the "docs" labelled issue page to welcome more documentation contribution.
    • License at the end (optional)

  2. User Level, to welcome more use of the project among speakers and by other conference organizers with following sections/pages.

    • Installation Guide for local and production environment for different platforms.
    • Quick Start / Getting Started guide, which will cover the steps after installation to use the project. A brief on how one can use the project to setup their CFP acceptance system.
    • Features the project offers
    • How-To(s) to setup and use the project as described here (migrate content from existing Github wiki over here)
    • FAQ section
    • Best Practices and speaker guidelines
    • Link to release notes page for the sake of history.

  3. Contribution page

    • Contribution guidelines with best practices to create a patch
    • License declaration
    • Pre-requisites such as git/python and django and sharing relevant resources
    • Redirection to easy-to-fix label issues on github
    • Community details, where to contact for help
    • Redirection to Development/developer page

  4. Development Page, for developers working on the project

    • Link to contribution guidelines
    • Getting started page link / Installation Page link
    • API resources

    • Structure of the project, detailing on the individual application

631

627

589

miphilomath commented 4 years ago

junction

palnabarun commented 4 years ago

@miphilomath -- Thank you for kicking this off. All of the above plans look good to me other than the following comment, How about removing the Developer Guide? API Reference and Project Structure are the proposed sections adding value. Project Structure can be documented in the Contributor Guide itself and API Reference can be a separate top-level section.

miphilomath commented 4 years ago

Yeah, I guess we can keep the contents of developer guide in contribution guide. I kept a separate developer page assuming that the page will grow bigger with details of Frontend and Backend components and applications detail later. But I guess, we can keep them in contribution guide until that happens.

Also, should I go ahead with the Pull request for the documentation as suggested above?