Skip to content

An opinionated, batteries-included template for project proposals with formatting boilerplate.

License

Notifications You must be signed in to change notification settings

philiplinden/project-definition-doc-template

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Project Definition Document Template

This is an opinionated, batteries-included template for project proposals with formatting boilerplate. It is a successor to rit-spec/SPEX-Project-Definition-Documents.

See the examples created from this template. There is also some reference material included here, like the original IEEE template and some example bibliography files with a variety of citation types.

What is a Project Definition Document?

The intent of a Project Definition Document (PDD) is to organize and document a project idea and its objectives. In the ideal project life cycle, an idea undergoes an initial research phase where an individual or a small team develops the primary objectives and requirements. The PDD is a snapshot of the known challenges, risks, and anticipated areas for research at the very start of a project.

Are all the sections in the template required?

Short answer: No.

Long answer: The template was written as a functional example. Read it! One reason to write a PDD is to guide you to focus and refine your project concept. Writing this document will hopefully guide you to think about how your project will grow in the future and and what major obstacles will be in your way. While many sections of the template are specific to the template as a PDD itself, I expect many of the same discussions to appear in your project as well.

Why use LaTeX instead of a regular word processor?

LaTeX is not a word processor. It allows you to write content without worrying about formatting or typesetting -- LaTeX handles all the organization, placement of text, spacing, headings, and so on. It is the de facto standard for technical and scientific documents, and it is beneficial for you to be at least somewhat familiar with using it, especially if you plan to do research in the future. For more about LaTeX, visit their homepage.

Using the template for your own PDDs

If you find a bug or encounter a persistent issue with the template, please create a new issue describing your problem so it can be fixed.

For answers to more frequently asked questions, see faq.md.

Fork the template

This is a template repository. It is meant to be forked and live a new life outside of this repo.

According to the official Github docs, Creating a repository from a template is similar to forking a repository, but there are important differences:

  • A new fork includes the entire commit history of the parent repository, while a repository created from a template starts with a single commit.
  • Commits to a fork don't appear in your contributions graph, while commits to a repository created from a template do appear in your contribution graph.
  • A fork can be a temporary way to contribute code to an existing project, while creating a repository from a template starts a new project quickly.

Get writing

  1. READ. Read a lot of technical writing, good AND bad. This will help you refine your skill while giving you goal posts to shoot for and pitfalls to avoid.

  2. WRITE. You don't get better without practice. Personal projects are a good safe place to do this because nobody sees the writing unless you share it. If you think it's good, its an amazing feeling to share a well documented project--it makes the project itself look that much better.

  3. DON'T OVERTHINK IT. With technical writing, the goal is to convey your ideas as completely yet as concisely as possible. Sometimes sharing too much detail can obstruct the main idea you're trying to convey. Likewise, not enough detail and the main idea gets lost or misunderstood. It's a balance that you'll discover with tips 1 and 2.

  4. DON'T TAKE IT PERSONALLY. Even if your words are written well, they can still be confusing. If someone reads your words and is confused, there is probably a good reason for that. Take mental notes of the way you explain it to them verbally and see if you can work that in to the original confusing bit. Every time you explain what you meant to say, that means there is an opportunity to improve what you wrote. Iteration is necessary 99.9% of the time. Don't let it get to you and keep writing. But don't let it get to your head--you can always write something better.

  5. FORMATTING COMES FIRST AND LAST. This one is tricky. What I mean is that when you block out your ideas just starting out a piece of writing, organize it in a way that makes the most sense for your mental model of what you intend to write. Build the scaffolding. For me, this includes lots of subheadings or bulleted lists. The framework usually lingers as comments. When writing the meat of it, don't get hung up on formatting. At that point your goal is to get the words out and into your scaffold. Finally, take some time to format things well. How words are arranged can have a significant impact on how they are received or understood. In short: Put up the frame, lay the pipes, electrical, and lights. Then put up the drywall and buy your furniture. Then paint the walls and rearrange the furniture. Then keep repainting and rearranging for the next 20 years.

Do the project

You don't need to be ready, you just need to go.

A technical report on what happened when you did the project is a great way to capture the process and lessons learned along the way. Explain the end result but also take the time to reflect and see how you can improve for next time.

See How to write a technical report.

About

An opinionated, batteries-included template for project proposals with formatting boilerplate.

Resources

License

Stars

Watchers

Forks

Languages

  • TeX 100.0%